Repository navigation
release: 2.4.0 — re-measured docs, a regenerated reference dossier, and three leaks closed - #53
Merged
Merged
Conversation
…avels .superpowers/ was matched only by .git/info/exclude, which is local to one clone and is never pushed. On a fresh clone or a second checkout its contents would have appeared as ordinary untracked files, one 'git add .' away from being committed. The repository's other local-only directories are already listed in the committed .gitignore; this puts .superpowers/ beside them.
…ckout Fourteen tracked verification and benchmark records under audit-docs/ embedded absolute paths from the machine that produced them. One went further: assay_oracle_verification_2026_10_20.json recorded a second project's working tree as its pythonpath and as the path of the package under test. None of this identifies an artifact -- the sha256 recorded beside each path does that -- so the paths are now written relative to the repository. The four sites that produced them are fixed too, otherwise the next run of any of these tools would write the absolute paths back: duplex_compile_benchmark, duplex_family_benchmark and original_end_stress each recorded extension_path from Path(_engine.__file__).resolve(). They now record it relative to the repository root, falling back to the basename for an extension installed outside it. After this, no tracked file in the repository names a path on anyone's machine.
requirements-docs.txt and two Makefile comments referenced docs/docs_mkdocs_migration_plan.md. docs/ is gitignored, so that document is not in the repository and never was: a reader following the reference finds nothing. requirements-docs.txt also gave its own install path as docs/requirements-docs.txt, which does not exist either; the file is at the repository root. The Makefile's docs comment additionally said the contributor-only markdowns live at docs/*.md -- they are at audit-docs/ -- and that 'docs-build' should be run in CI 'once Phase 6 cutover lands'. It already is, by .github/workflows/deploy-docs.yml, on every docs change.
422 commits since 2.3.1 moved what the documentation describes, and the documentation did not follow. Each claim here was checked by running it, not by reading the code around it. Examples that could not work as written: the README's custom RefDataConfig block had a literal '.' in a nucleotide string and an anchor past the end of a 21-nt sequence; two species examples raise on a quarantined catalogue entry without .allow_curatable_refdata(); a paired-end example asked for a 450-nt insert on a molecule that is 352-436 nt; an NpBaseModelSpec example passed a set where a 4x4 matrix belongs; a sequencing-errors block printed the previous block's record because it never rebound its variable. Claims that were false rather than stale: productive_only() was documented as refusing TCR references, and it does not; S5F was attributed to Shapiro rather than Yaari et al. (2013), and described as concentrating in the CDRs, which its kernel has no way to do; a paired-end window was said to clip to what is available, when it raises; sequence case was documented inverted. Quantities were re-counted rather than adjusted: 40 names in __all__, 106 catalogue entries of which 80 are quarantined, nine performance workloads, six estimators, over 120 validated AIRR fields. n_max and lambda_base are described as the engine now defines them: n_max is the population a lineage settles at under Beverton-Holt, not a ceiling, and lambda_base is the Poisson mean for a founder-baseline cell in an empty germinal center rather than the mean once damping or selection applies. A wrong-length affinity target is refused, not scored over its prefix. The determinism promise is stated with its scope: same seed and same determinism_version gives byte-identical output, checked by the reproducibility goldens on Linux, macOS and Windows across Python 3.10-3.13, with aarch64 named as shipping a wheel that nothing compares. It previously promised platform independence with no version and no scope at all. expand_clones()'s DeprecationWarning appeared on no page; genotypes appeared nowhere in the README. Both do now. CONTRIBUTING.md said GenAIRR ships two PyPI packages and that a release updates setup.py; it ships one wheel and there is no setup.py. Thirty-seven unwritten pages carried a placeholder linking to a gitignored internal plan, so every one of those links was a 404 on the published site. Each now points at the page that actually covers the material.
The changelog leads with the one fact that matters to anyone holding data: a seed does not reproduce 2.3.1's output any more. DETERMINISM_VERSION moved through 2, 3 and 4 in this cycle, each increment moving what a seed draws, and the entry gives a row per version so a stored dataset can be placed. A dataset with no determinism_version column was drawn by the pre-2.4.0 model. The breaking section also carries the lineage regulation change -- the same n_max now settles roughly three times the population it used to cap -- the expand_clones() deprecation, and the catalogue quarantine that makes 80 of 106 entries refuse to compile without an explicit opt-in. MIGRATING.md gains a 2.3.1 section ahead of the 1.x guide: keep the file rather than the seed, convert n_max by dividing by three at the default lambda_base, and six smaller breakers including pandas no longer arriving with any extra and summary() returning a dict. Every runnable snippet in it was executed.
The version bump alone fails four tests, which is the guard working: the packaged reference dossier records the GenAIRR version that generated it, so a checkout declaring 2.4.0 beside a dossier built by 2.3.1 is a mismatch the suite refuses. The generator refuses too, until the installed build matches what pyproject declares, so the dossier cannot be stamped with a version it was not built by. This would have broken the release rather than the local run: build-wheels.yml patches pyproject.toml from the tag and then runs 'pytest tests/ -x -q', and nothing in that workflow can regenerate a 20 MB artifact. The archive has only existed since 2026-10-27, after the v2.3.1 tag, so no release has passed through this guard before. Of the five pinned digests the generator names, two moved: the manifest hash and the raw archive hash, both of which cover the recorded version. The runtime execution, catalogue and models hashes and the source lock came back byte-identical, and the archive is the same 20110025 bytes, which is the evidence that nothing about the reference build itself changed. The two retargeted pins are declared for the inventory gate, which cannot see a constant's new value by hashing bodies.
duplex_compile_benchmark and duplex_family_benchmark import _engine inside the functions that use it, not at module scope, because they re-enter themselves as worker subprocesses. The helper added in the previous commit was placed at module scope and referenced _engine from there, so ruff's F821 rejected both files and every Python job failed on the lint step. original_end_stress imports _engine at module scope and was unaffected, which is why only two of the three were flagged. The helper now takes the import locally, matching each module's own idiom. Checked by running all three: each returns src/GenAIRR/_engine.abi3.so. 'make validate-release' does not lint, so this could not fail locally; 'ruff check tests/ src/ tools/' is the command CI runs and now passes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Release preparation for 2.4.0. Six commits, one theme each.
What a user gets
DETERMINISM_VERSIONis 4. A seed does not reproduce 2.3.1's output any more, which the changelog leads with andMIGRATING.mdgives a procedure for. The samen_maxnow settles roughly three times the population it used to cap.The documentation was re-measured, not reviewed
422 commits since 2.3.1 moved what the docs describe. Every claim touched here was checked by running it. The failures found were not all staleness:
.in it and an anchor past the end of a 21-nt sequence; two species examples that raise on a quarantined catalogue entry; a paired-end example asking for a 450-nt insert on a 352–436-nt molecule; anNpBaseModelSpecgiven a set where a 4×4 matrix belongs.productive_only()was documented as refusing TCR references, and it does not. S5F was attributed to Shapiro rather than Yaari et al. (2013), and described as concentrating in the CDRs, which its kernel has no mechanism to do. A paired-end window was said to clip to what is available, when it raises.Three things that should not have been in the repository
requirements-docs.txtand two Makefile comments pointed at a document that is gitignored and therefore not in the repository..superpowers/was ignored only by.git/info/exclude, which never travels — on a fresh clone its contents were onegit add .from being committed.The version bump failed four tests, and that was the guard working
The packaged reference dossier records the GenAIRR version that generated it, so a checkout declaring 2.4.0 beside a dossier built by 2.3.1 is a mismatch the suite refuses — and the generator refuses too, until the installed build matches what
pyproject.tomldeclares.This would have broken the release, not the local run.
build-wheels.ymlpatchespyproject.tomlfrom the tag and then runspytest tests/ -x -q, and nothing in that workflow can regenerate a 20 MB artifact. The archive has only existed since 2026-10-27, after the v2.3.1 tag, so no release has passed through this guard before.Of the five pinned digests, two moved — the manifest hash and the raw archive hash, both covering the recorded version. The runtime execution, catalogue and models hashes and the source lock came back byte-identical, and the archive is the same 20110025 bytes. That is the evidence that nothing about the reference build itself changed.
Verification
make validate-release— 5887 passed, 17 skipped, 0 failed; Rust1602 passed; 0 failed;genairr-2.4.0-cp39-abi3-manylinux_2_34_x86_64.whlbuilt.mkdocs build --strictexits 0; the docs and meta contract tests pass 71/71.tools/inventory_gate.py check --since origin/master --declarations— clean.Known, deliberately not hidden
site_docs/guides/clonal-families.md's example still raises at seed 0: 1 of 294 records reportsrecalled_d_callasIGHD5-18*02where the evidence is a tie,IGHD5-18*02,IGHD5-12*01. Truth is present and first; the tied second allele is dropped. It is lineage-specific — the ordinary path at a higher mutation rate over 2000 records is clean, while the lineage path shows 1 in 2437 across 8 seeds.The page was left raising rather than switched to a passing seed, which would have hidden a real defect in the page that teaches the feature. Fixing it moves the clonal goldens, so it is its own change.